Inside Macintosh: QuickDraw GX Objects /

Chapter 8 - Tag Objects / Tag Objects Reference

Functions / Creating and Manipulating Tag Objects

GXCopyToTag

You can use the GXCopyToTag function to copy the contents of one existing tag object into another, or to create a new tag object and copy the contents of an existing tag object into it.

gxTag GXCopyToTag(gxTag target, gxTag source);

target

A reference to the tag object to copy into. If you specify nil for this parameter, the GXCopyToTag function creates a new tag object.

source

A reference to the tag object whose contents you want to copy.

function result

A reference to the copy (that is, the target tag object).

DESCRIPTION

The GXCopyToTag function copies the contents of an existing tag object to another, or it creates a new tag object and copies the contents of an existing tag object to it. The function copies the tag type and contents (but not the owner count) of the tag object specified by the source parameter into the tag object specified by the target parameter.

If you specify nil for the target parameter, the GXCopyToTag function creates a new tag object and copies the source tag object's tag type, contents, and owner count into it.

You can use the GXCopyToTag function to create a copy of a tag object and then modify it without changing the original.

SPECIAL CONSIDERATIONS

If you specify nil for the target parameter and no error occurs, the GXCopyToTag function creates a tag object; you are responsible for disposing of that object when you no longer need it.

If you attempt to alter a tag object associated with a screen view device, this function posts a tag_access_restricted error.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
tag_is_nil
tag_access_restricted	(debugging version)

SEE ALSO

To create a new tag object that is not a copy of an existing tag object, use the GXNewTag function, described on page 8-13.

To compare two tag objects, use the GXEqualTag function, described in the next section.